Roller

	This plug-in is written in Python 2.7 for GIMP v2.10. Roller is designed to create image compositions like wallpaper, image boards, collages, etc. Roller 1 through 3 presets are incompatible with Roller 4.

Basics

	Steps

	Roller breaks a render into steps. Steps are how an option group produces layer output and a step layer group. Global, Gradient Light, Backdrop are examples of an option group, each having a step. Some steps have a sub-step. A sub-step will produce an additional layer in the step's layer group.

    A View Button
    
    A view button when activated causes steps to be processed. There are two basic view types: Plan and a work-in-progress (work). For each basic view, there are two process options, a partial and a complete view. For planning, draft produces a partial plan. A partial view ends its output on the option group visible in the main window. When working, the Peek option is the partial option, while an activated Preview makes a complete view.

	Composition

	Roller creates layers like a pancake robot in a sci-fi movie, but the Backdrop Image layer and the Gradient Light output deserve a mention.

	Every composition has a Backdrop Image layer. This layer serves as a backdrop for the composition and may provide material for a Backdrop Style. Many Backdrop Styles depends on the alpha in the Backdrop Image layer. The style's tool-tip will indicate this dependency.

	Gradient Light is a gradient that is used in multiple parts of a render. It's purpose is to simulate a light source or an environment, but it has other uses, such as unifying a composition.

Model

	Each model offers unique possibilities for composing. Roller 4 has four models: Table, Cell, Stack and Box. Models share some common characteristics. They all have a Property option group and a Cell branch with a Cell Type.

    After creating a model, steps need to be added to the navigation tree in order to produce layer output. Select the Model Step button in the Model group to choose steps.

	Table
	
	The Table model has two branches: Canvas and Cell. The Canvas branch has options for modifying the canvas rectangle. The Cell branch is very much like the Canvas branch, except for the options apply to a cell rectangle.

	Table divides the canvas into a grid defined by row and column counts. Row and column intersections form a cell. The main window options apply to the entire grid. If a single cell needs to modified, the Per Cell option can be used.

	The Per Cell option when selected provides access to a cell table layout which in turn opens a Cell Editor. The Cell Type Per Cell option however only has a merge cell layout.

	Cell
	
	The Cell model has one branch: Cell. A Rectangle option defines a single cell rectangle for its output.

	Stack
	
	A Stack model has one branch, and like Cell, uses a Rectangle option to define its first cell. When Stack has more than one cell, the Add Offset X and Add Offset Y options modify the additional cell rectangle positions. For each cell after the first, the offsets are added to the previous cell rectangle's position to determine the next cell's top-left position.

	Box
	
	The Box model has three branches: Canvas, Cell, and Face. The Box grid is the same grid as the Table's hexagon-shaped cell. It's a double-spaced grid where every other cell is valid. A Face option group applies itself to each of the three faces on the Box.

	Pyramid

	A Pyramid model has two branches, Canvas and Cell. A cell is assigned with a row and its column count. The row divides its span by the column count to define the cell width. The cell height is calculated from the total number of row and the canvas space. The wide end of the Pyramid is the row one location. If the Pyramid is facing up, then row one is at the bottom. If the Pyramid is facing down, row one is at the top of the Pyramid render.

Insight

	Cell Rectangle

	Every cell has a rectangle that defines a cell bounds. A cell's shape its determined by this limitation. However, there are other rectangles that effect how the final cell output, such as, the Shift and Margin options.

	Shift

	The Shift options adjust a rectangle's size and position. There are Canvas and Cell versions of Shift. The Cell version may have a Per Cell option which can change a single cell's rectangle.
	
	Margin

	Margin options apply inside a cell rectangle. They produce a pocket rectangle. An Image option group is always limited to the pocket, but other option groups have an Obey Margins options which, when off, causes the output to ignore the pocket limitation.

	Cell Shape
		
	A cell shape has two variations. The cell rectangle defines the original shape of the cell. If margins apply, then there is an additional cell shape created. Option groups will use one or the other cell shape when masking and sizing layer output.

	Image Mold

	The image Mold process ensures that an image fits inside a pocket. If an image is larger than its pocket, the image may be scaled down depending on the Resize Method. On the other hand, depending on the Resize Method and image justification, an image may be enlarged in order to fill a pocket.

Adding Frames to the Frame Folder
		
	During start-up, Roller compiles a list of '.png' file types from Roller's Frame folder. You can add additional frames to this folder. In order to add your own frames, they must be the '.png' file type. The frames are used solely by the Frame/Frame Over option. Gratitude to dinasset from 'gimpchat.com' for sharing the frame files.

Errors And Limitations To Be Aware Of

	* If an image is referenced from a File or Folder image source is displaying black instead of image material, try converting the image to GIMP's sRGB color profile prior to running Roller.

	* There's a problem with the Color Picker dialog that is provided by the outdated GTK 2.0. There's an Entry widget next to the opacity slider that doesn't actually modify the opacity setting. The opacity slider works as advertised though.

	* Opening and closing images in GIMP while Roller is open may make Roller unstable.

	* Putting too many rows and columns into a composition grid may result in a crash. GTK has its limitations, and Roller doesn't compensate for a grossly large scale. The Merge Cells window may come to a crawl when drawing a multitude of cells. I was able to create a grid of 15 rows and 15 columns without too much of a delay. So patience may be in order if you wish to create a larger grid of cells.

	* I recommend having the Layer Dock visible while running Roller as this dock will show GIMP working.

	* Roller doesn't save images. Only Preset files in Roller Preset folder are saved.

	* Two running Roller scripts will likely crash into each other.

	* When the script is run for the first time, Python creates ".pyc" type files within the Module folder. These files help the code run faster in the Python interpreter. The files are re-created if they go missing, so no worries about deleting them.

      * Some dynamic brushes, when applied as brush stroke, may not work with Brush Punch and and Fringe. I have no idea why. If you know, please let me know.

	* Roller uses the clipboard to make image snapshots. If there is another background process also using the clipboard, then this can cause the copy and paste operation to fail resulting in a completely black output.

	* Testing and designing a composition can be sped up in several ways.
		1) Reduce the size of the render.
		2) Turn off unused option groups.
		3) Move steps to the model list shelf.
		4) Be mindful of the background update layers:
		   Average Color, Backdrop, and Blur Behind.

	* It's safe to adjust layer opacity and mode in the Layer Dock while Roller is idle. However, Roller won't see these kind of changes during its processing.

Links
	These are GIMP-related sites worth visiting:

	* I post the latest version of my GIMP plug-ins on GitHub under my GummyCowboy user-name:
	github.com/gummycowboy

	* GIMP Forum:
	gimpchat.com
	gimp-forum.net
	reddit.com/r/GIMP/

	* Plug-in:
	gimpscripts.net
	sourceforge.net/projects/gimp-tools
	magentacloud.de/share/x2qpdqu2g4#$/Plug-Ins
	kmarkku.arkku.net/Path_modify_files/Gimp_master.html
	gmic.eu
	gitlab.gnome.org/GNOME/gimp/-/tree/gimp-2-10
	gimpbook.com/scripting/
	github.com/karlhof26/

	* Other Art-related:
	gimp-forum.net/Thread-Paths-Basics
	alessandrofrancesconi.it/projects/bimp
	discuss.pixls.us

	* GEGL:
	gegl.org/operations
	gimpchat.com/viewtopic.php?f=9&t=18040
	gimp-forum.net/Thread-Scripting-GEGL-operations
	samjcreations.blogspot.com/2020/09/est-une-bibliotheque-image-libre-tres.html
	gimpchat.com/viewtopic.php?f=10&t=19463
	gimpchat.com/viewtopic.php?f=8&t=19469&sid=c995dfef16cb8fec9af5ea6bcb308601
	gimpchat.com/viewtopic.php?f=9&t=20055&sid=ae93b13c28f1bb01aed875382dafe4f9
	barefootliam.blogspot.com/2022/10/gegl-plug-ins-for-gimp-part-one-using.html
	barefootliam.blogspot.com/2022/12/gegl-plug-ins-for-gimp-part-two-gegl.html
	barefootliam.blogspot.com/2023/01/gegl-plug-ins-for-gimp-part-three.html

	* Frames:
	gimpchat.com/viewtopic.php?f=9&t=11486

	* Wrap an image around an object:
	youtube.com/watch?v=rUp3-XxZl0E
	youtube.com/watch?v=qoTjcXR_bFk

	* PyGTK
	Reference Manual:
	wiki.python.org.br/DocumentacaoPython?action=AttachFile&do=get&target=ref.pdf
	developer-old.gnome.org/pygtk/stable/

	Documentation:
	library.isr.ist.utl.pt/docs/pygtk2reference/
	developer.gimp.org

	* Tutorial:
	developer.ibm.com/articles/os-autogimp/
    littlewebhut.com/gimp/
	graphicdesign.stackexchange.com/questions/87247/creating-a-realistic-gold-surface-in-gimp
	
	* Python
	gimp.org/docs/python/
	discuss.pixls.us/t/gmic-tutorial-fragments/24289/63
	gmic-py.readthedocs.io/en/latest/gettingstarted.html#run-a-simple-g-mic-effect-and-view-it
	inventwithpython.com/bigbookpython/
	docs.python.org/3/library/2to3.html
    projects.raspberrypi.org/en/codeclub/python-module-1
	automatetheboringstuff.com/2e/chapter0/
	pythondiscord.com/resources/
	wiki.python.org/moin/BeginnersGuide
	practicalpython.yasoob.me/toc.html
	gto76.github.io/python-cheatsheet/

	* Get GIMP ("GNU Image Manipulation Program")
	gimp.org

	* YouTube
	Rich2005
	Make a GIMP Brush
	youtube.com/watch?v=3mZ9vF2ayM0

	Davies Media Design
	youtube.com/channel/UCq79-lfj2w7oRXGRcOP2B7g

	tutor4u
	youtube.com/watch?v=ToHF7OhkjTM&list=PLA4BBBE09E8E82409

	Jackson Bates - GIMP Scripting Python Fu Playlist
	youtube.com/watch?v=cPQRxZo9BJE&list=PLyRItRv4aHfOuUC8a1SMeTLV08wxdnWt-&index=1

	D R
	How to clean up edges
	youtube.com/watch?v=wchU1_skBwU

	Rafik Graphics
	youtube.com/@rafikgraphics

Special Thanks

	Many thanks to the free programs Notepad++ (for easy editing), Visual Studio Code (for syntax checking), and PyCharm (for detailed code analysis). Each is a great Python code editor. Also, I would like to give a special thanks to every GIMP plug-in author for sharing their inspirational work.

	- Charles Bartley
	August 20, 2023
